The AGILE Scientific Ratemeter files contain the photon counts recorded by every AGILE instrument:
The counts recorded are integrated in the energy range of the detector and in time bins of fixed width of 1.024 s, with the exception of the SuperAGILE ratemeters which use bins of 0.512 s.
The ratemeter files (the so-called "3913" files) are provided in a compressed FITS Format optimized for data download from the satellite. One file was produced for every satellite contact.
Agilepy implements a AGRatemeters class that reads the ratemeters files and extract the Ratemeters Light Curves.
The Light Curves can be used to check for transient phenomena, and if the Burst Onest Time (T0) of a Burst is provided, the significance and duration of the Burst can be estimated.
The Analysis of the Scientific Ratemeters follows these general steps:
YAML configuration file for AGRatemeters. You can do it manually or by using AGRatemeters.getConfiguration().AGRatemeters object, and read the 3913 file with AGRatemeters.readRatemeters().AGRatemeters.plotRatemeters() function, perform a simple Aperture Photometry analysis with AGRatemeters.analyseSignal(), perform a basic estimation of the burst duration with AGRatemeters.estimateDuration().In this notebook, we show examples for two GRBs.
Note: each instrument is pointed in a different direction. In particular, AC4 is always pointed towards the Sun.
# Import the relevant classes
import agilepy
from agilepy.api.AGRatemeters import AGRatemeters
# Prepare the YAML Configuration File.
# You can create it manually or use AGRatemeters.getConfiguration()
outputDir1 = "/home/flareadvocate/workspace/shared_dir/"
confFilePath1 = "/home/flareadvocate/workspace/shared_dir/tutorial_rm_GRB221018A.yaml"
AGRatemeters.getConfiguration(
confFilePath=confFilePath1,
outputDir=outputDir1,
userName="my-name",
sourceName="rm-source",
verboselvl=0,
filePath="$AGILE/agilepy-test-data/ratemeters/PKP080686_1_3913_000.lv1.cor.gz",
timetype="isot",
T0="2022-10-28T13:16:27",
background_tmin=-50.0,
background_tmax=-20.0,
signal_tmin=-1.0,
signal_tmax=3.0
)
The YAML file has the following sections and field:
output: common to all agilepy classes, sets the output fields.selection: includes one argument used to read the data:filePath: path to the input file.analysis: includes arguments for plots and further analyses:timetype and T0: Format and value of the Burst Oneset Time. It can be TT or OBT for AGILE seconds (TT seconds since 2004-01-01 00:00:00.000), or a format acknowledged by the astropy.time.Time class. T0 will be converted in AGILE seconds and used as reference time for plots and analyses.background_tmin and background_tmax: time range used for evaluation of the background, in seconds with respect to T0.signal_tmin and signal_tmax: time range used for evaluation of the signal, in seconds with respect to T0.# Create the AGRatemeters object
ag_rm1 = AGRatemeters(confFilePath1)
Log level set to WARNING and output to /home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211100/logs
# You can Use the setOptions() method to change the configuration, e.g.:
ag_rm1.setOptions(background_tmin=-50.0, background_tmax=-10.0)
# Check configuration.
ag_rm1.printOptions()
{ 'analysis': { 'T0': 594047787.0,
'background_tmax': -10.0,
'background_tmin': -50.0,
'signal_tmax': 3.0,
'signal_tmin': -1.0,
'timetype': 'TT'},
'output': { 'filenameprefix': 'ratemeters_product',
'outdir': PosixPath('/home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211100'),
'sourcename': 'rm-source',
'username': 'my-name',
'verboselvl': 0},
'selection': { 'file_path': '/home/flareadvocate/agiletools/agilepy-test-data/ratemeters/PKP080686_1_3913_000.lv1.cor.gz'}}
Read the Ratemeters with AGRatemeters.readRatemeters(writeFiles).
Optional aguments are:
filePath: if None (default), it will be read from the configuration. Otherwise, the function will read the file from the path provided explicitly.writeFiles: if True (default), write the Light Curves as .txt files.The method will return a dictionary of tables, one per instrument, with the ratemeter Light Curve.
They can be accessed using the instrument name as a key.
The tables can also be accessed via the AGRatemeters.ratemetersTables property.
Each Table has 3 columns:
OBT: detection time in AGILE secondsCOUNTS: counts measuredCOUNTS_D: counts de-trended with a FFT algorithm to remove background modulation due to the orbital motion and spinning of the satellite.# Read the ratemeter file
ratemeters_tables = ag_rm1.readRatemeters()
/home/flareadvocate/Agilepy/agilepy/api/AGRatemeters.py:130: RuntimeWarning: divide by zero encountered in scalar divide data_yf = (2 / np.sum(values)) * abs(scipy.fftpack.fft(values))**2 #* scipy.fftpack.rfft(y) /home/flareadvocate/Agilepy/agilepy/api/AGRatemeters.py:130: RuntimeWarning: invalid value encountered in multiply data_yf = (2 / np.sum(values)) * abs(scipy.fftpack.fft(values))**2 #* scipy.fftpack.rfft(y)
# The Light Curves are stored in Tables, and can be accessed via Dictionary
print(ratemeters_tables.keys())
# E.g. access the AC Top table
display(ratemeters_tables['AC0'])
# The Dictionary can be accessed also via property
display(ag_rm1.ratemetersTables['MCAL'])
dict_keys(['GRID', 'MCAL', 'SA', 'AC0', 'AC1', 'AC2', 'AC3', 'AC4'])
| OBT | COUNTS | COUNTS_D |
|---|---|---|
| float64 | int32 | float64 |
| 594047441.602208 | 2926 | 3156.8248533042997 |
| 594047442.6262081 | 2887 | 3124.333154382883 |
| 594047443.650208 | 3008 | 3251.9585105203537 |
| 594047444.674208 | 3116 | 3366.699623659409 |
| 594047445.698208 | 3177 | 3434.5546431971634 |
| 594047446.722208 | 2848 | 3112.521122809405 |
| 594047447.7462081 | 3130 | 3401.5959827584365 |
| 594047448.770208 | 3109 | 3387.775478156238 |
| ... | ... | ... |
| 594053444.714912 | 3154 | 3336.9875599624684 |
| 594053445.7389121 | 3225 | 3413.561361842546 |
| 594053446.762912 | 3422 | 3616.249256148664 |
| 594053447.7869121 | 3388 | 3588.0523412390567 |
| 594053448.810912 | 3342 | 3547.9716359251147 |
| 594053449.8349121 | 3085 | 3297.0080139731317 |
| 594053450.8589121 | 3306 | 3524.1621390686196 |
| 594053451.882912 | 3220 | 3444.434400936505 |
| OBT | COUNTS | COUNTS_D |
|---|---|---|
| float64 | int64 | float64 |
| 594047441.602208 | 1218 | 1180.354681306513 |
| 594047442.6262081 | 1262 | 1224.5227916500485 |
| 594047443.650208 | 1274 | 1236.7284040401562 |
| 594047444.674208 | 1248 | 1210.9728004749263 |
| 594047445.698208 | 1257 | 1220.2571625405335 |
| 594047446.722208 | 1194 | 1157.582555424022 |
| 594047447.7462081 | 1168 | 1131.949912832763 |
| 594047448.770208 | 1186 | 1150.3600229896524 |
| ... | ... | ... |
| 594053444.714912 | 1278 | 1240.1864978404471 |
| 594053445.7389121 | 1246 | 1208.1071081434036 |
| 594053446.762912 | 1196 | 1158.053424459286 |
| 594053447.7869121 | 1178 | 1140.0269074512476 |
| 594053448.810912 | 1231 | 1193.0290561221693 |
| 594053449.8349121 | 1230 | 1192.0613911318853 |
| 594053450.8589121 | 1166 | 1128.1254375638737 |
| 594053451.882912 | 1234 | 1196.2227073174276 |
Plot the Ratemeters with AGRatemeters.plotRatemeters().
The function has the following arguments:
plotRange: time limits of the plot in seconds with respect to T0.useDetrendedData: if True, use the De-trended counts, if False the raw counts.plotInstruments: list of instruments to plot in asingle plot. Possible values are "AC0","AC1","AC2","AC3","AC4","MCAL","GRID","SA".# Plot the Ratemeters
plots = ag_rm1.plotRatemeters(plotRange=(-100,100), useDetrendedData=True, plotInstruments=["3RM","GRID","AC4"])
# This combination will produce two plots:
# the "3RM" (SA, AC0, MCAL) + one with the instruments lsited explicitly (AC0, MCAL)
# It returns the List of Plots saved.
print(plots)
[PosixPath('/home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211100/plots/ratemeters_D_3RM.png'), PosixPath('/home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211100/plots/ratemeters_D_GRID_AC4.png')]
# The Raw Data can show the Orbital Modulation of the Background of each detector
# Due to the satellite motion and spinning
plots = ag_rm1.plotRatemeters(plotRange=(-200,200), useDetrendedData=False, plotInstruments=["2RM"])
# List of Plots
print(plots)
[PosixPath('/home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211100/plots/ratemeters_ND_2RM.png')]
A simple Aperture photometry analysis can be performed with AGRatemeters.analyseSignal()
Optional arguments (with default values shown) are:
backgroundRange=(None,None): Time Range for Background Estimation. If None, they are read from the configuration.signalRange=(None,None): Time Range for Signal Estimation. If None, they are read from the configuration.useDetrendedData=True: boolean flag for the de-trended data.The method returns a table with the number of counts recorded in the Signal and Background intervals (ON and OFF), the duration of the intervals (which are always multiples of 0.512s for SuperAGILE and 1.024s for the other detectors), the estimation of the Background Rate in cts/s and the Li&Ma Significance.
results = ag_rm1.analyseSignal(backgroundRange=(-20,-15), signalRange=(-1,3), useDetrendedData=True)
display(results)
| instrument | t_ON | N_ON | t_OFF | N_OFF | R_BKG | lima |
|---|---|---|---|---|---|---|
| str4 | float64 | int64 | float64 | int64 | float64 | float64 |
| GRID | 3.072 | 47584 | 4.201 | 65508 | 15593.43 | 1.11 |
| MCAL | 3.072 | 5519 | 4.201 | 5830 | 1387.765 | 13.712 |
| SA | 3.584 | 0 | 4.713 | 0 | 0.0 | 0.0 |
| AC0 | 3.072 | 14263 | 4.201 | 16772 | 3992.383 | 13.22 |
| AC1 | 3.072 | 12468 | 4.201 | 14461 | 3442.276 | 13.442 |
| AC2 | 3.072 | 12592 | 4.201 | 14329 | 3410.855 | 15.005 |
| AC3 | 3.072 | 10043 | 4.201 | 12016 | 2860.271 | 9.861 |
| AC4 | 3.072 | 12183 | 4.201 | 14944 | 3557.248 | 8.889 |
A simple estimation of the Duration of the Burst can be performed with AGRatemeters.estimateDuration().
Its arguments are (with default values shown) are:
dataRange: Time Range for the Plot. Must include Background and Signal.backgroundRange=(None,None): Time Range for Background Estimation. If None, they are read from the configuration.signalRange=(None,None): Time Range for Signal Estimation. If None, they are read from the configuration.useDetrendedData=True: boolean flag for the de-trended data.plotDuration: If True, plot the Differential and Cumulative, Background-subtracted Light Curves.The plot include the Background-subtracted, differential and Cumulative Light Curves of SA, MCAL, AC0 (if activated). The red (blue) bands identify the background (signal) range, and the green lines the region where the signal is significantly rising.
results, plot = ag_rm1.estimateDuration(dataRange=(-50,50),backgroundRange=(-50,-10),signalRange=(-1,3),useDetrendedData=False)
# The result is a dictionary for every instrument.
# For every instrument, the arrays of counts are recorded, and also an estimate of the duration
results_mcal = results['MCAL']
print(results_mcal.keys())
print(f"Burst duration estimated from MCAL: {results_mcal['duration']:.4g}s")
results_ac0 = results['AC0']
print(f"Burst duration estimated from AC0: {results_ac0['duration']:.4g}s")
# Path of the saved Image
print(plot)
2025-08-11 21:11:11 | WARNING | agilepy.api.AGRatemeters.AGRatemeters | Detector SA not active. | (AGRatemeters.py:1321)
dict_keys(['time', 'counts', 'counts_bkgsub', 'integral_counts', 'sigrise_time', 'duration']) Burst duration estimated from MCAL: 3.072s Burst duration estimated from AC0: 1.024s /home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211100/plots/ratemeters_duration_ND.png
# Configuration
outputDir2 = "/home/flareadvocate/workspace/shared_dir/"
confFilePath2 = "/home/flareadvocate/workspace/shared_dir/tutorial_rm_GRB231129C.yaml"
AGRatemeters.getConfiguration(
confFilePath=confFilePath2,
outputDir=outputDir2,
userName="my-name",
sourceName="rm-source",
verboselvl=0,
filePath="$AGILE/agilepy-test-data/ratemeters/PKP086465_1_3913_000.lv1.cor.gz",
timetype="isot",
T0="2023-11-29T19:10:18",
background_tmin=-50.0,
background_tmax=-25.0,
signal_tmin=-2.0,
signal_tmax=10.0
)
# Create the AGRatemeters object
ag_rm2 = AGRatemeters(confFilePath2)
# Check Options
ag_rm2.printOptions()
Log level set to WARNING and output to /home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211111/logs
{ 'analysis': { 'T0': 628369818.0,
'background_tmax': -25.0,
'background_tmin': -50.0,
'signal_tmax': 10.0,
'signal_tmin': -2.0,
'timetype': 'TT'},
'output': { 'filenameprefix': 'ratemeters_product',
'outdir': PosixPath('/home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211111'),
'sourcename': 'rm-source',
'username': 'my-name',
'verboselvl': 0},
'selection': { 'file_path': '/home/flareadvocate/agiletools/agilepy-test-data/ratemeters/PKP086465_1_3913_000.lv1.cor.gz'}}
# Read ratemeters
ratemeters = ag_rm2.readRatemeters()
/home/flareadvocate/Agilepy/agilepy/api/AGRatemeters.py:130: RuntimeWarning: divide by zero encountered in scalar divide /home/flareadvocate/Agilepy/agilepy/api/AGRatemeters.py:130: RuntimeWarning: invalid value encountered in multiply
# Plot Light Curves
plots = ag_rm2.plotRatemeters(plotRange=(-60,60), useDetrendedData=True, plotInstruments=["2RM"])
print(plots)
[PosixPath('/home/flareadvocate/workspace/shared_dir/my-name_rm-source_20250811-211111/plots/ratemeters_D_2RM.png')]
# Aperture Photometry
results = ag_rm2.analyseSignal(useDetrendedData=True)
display(results)
| instrument | t_ON | N_ON | t_OFF | N_OFF | R_BKG | lima |
|---|---|---|---|---|---|---|
| str4 | float64 | int64 | float64 | int64 | float64 | float64 |
| GRID | 10.245 | 170722 | 23.566 | 340199 | 14436.01 | 47.991 |
| MCAL | 10.245 | 15069 | 23.566 | 27578 | 1170.245 | 22.299 |
| SA | 11.269 | 0 | 24.59 | 0 | 0.0 | 0.0 |
| AC0 | 10.245 | 46433 | 23.566 | 72709 | 3085.335 | 63.654 |
| AC1 | 10.245 | 36319 | 23.566 | 67797 | 2876.899 | 31.756 |
| AC2 | 10.245 | 34234 | 23.566 | 64251 | 2726.428 | 30.069 |
| AC3 | 10.245 | 31118 | 23.566 | 53603 | 2274.591 | 40.004 |
| AC4 | 10.245 | 42417 | 23.566 | 69896 | 2965.968 | 53.355 |
# Estimate Duration
result_dict, plot = ag_rm2.estimateDuration(dataRange=(-60,60), useDetrendedData=False)
print(f"Burst duration estimated from MCAL: {result_dict['MCAL']['duration']:.4g}s")
2025-08-11 21:11:25 | WARNING | agilepy.api.AGRatemeters.AGRatemeters | Detector SA not active. | (AGRatemeters.py:1321)
Burst duration estimated from MCAL: 9.221s